Introduction

This article is part of the XPages Extensibility API Developers Guide.

Deploying an XPage Library on a 8.5.2 Domino Server

In Lotus Domino Server 8.5.2 there is a new deployment method as we have moved to having an OSGi™ framework on the server. The OSGi technology is a Java based framework for running code in bundles or plug-ins. It now handles the loading of the XPages runtime and that means it also handles the loading of XPage libraries.

In previous releases users will be familiar with deploying their third party Java library jars to c:\Domino\xsp\shared\lib. For 8.5.2 your third party library jars will continue to work if they are located in \xsp\shared\lib but we recommend that you think about moving them to the new directories as plug-ins and features if possible.

To deploy an XPage library, you need to take the installed versions of your feature and plug-in and place them in the data\domino\workspace\applications\eclipse\features and data\domino\workspace\applications\eclipse\plugins directories respectively. Here is a link to the previous article about "Creating an XPages Library".




Restart your server and your library has been installed and is ready to use.

Common Server Problems

Accidentally putting your library in Notes\osgi\ folder instead of the Domino\osgi\ folder. There is an \osgi\ folder on the Notes client also which is used for the web preview if the application is local . It can sometimes be confusing if your moving around environments so be careful not to place your library there instead of the Domino osgi directory.

Using the built version of the plug-ins and features from the update site directly. The installed version should be used instead, as the update site contains all plug-ins and features as single jars, while an installed version will extract the feature to a folder containing files, and may extract the plug-in to a folder, depending on the settings in the feature.xml. By default an eclipse installer will will extract plug-in jars to a folder, only installing them as an unextracted jar when unpack="false" is set in the feature.xml file.

Deploying an XPages Library in a 8.5.2 Notes Client

We are leveraging the Widgets technology that was introduced in Lotus Domino 8.5.1 which allows administrators to install widgets on their clients via policies or eclipse preferences pushed down from the Domino Server or alternatively allows users to install libraries from their MyWidgets sidebar as they need, provided they have the appropriate privileges.

Creating the Widget Catalog

As an administrator you would create a new Widget Catalog like below on a Domino Server. A widget catalog is a server based application that centrally manages all your widgets or in our case, it is going to manage our XPage Library.

Create an Updatesite nsf that contains the plug-ins and features

After completing the steps in the previous article to create the plugin and feature for your library. There is an Eclipse Update Site template that can be used to host the plug-ins and features. It then can be used to import the plug-ins so that they can be provisioned to client machines using the widget definition that we will create in the next section.





After creating the updateSite, you just need to point it at the site.xml of your library update site that we created earlier. It will import the plug-ins and features into the nsf.





There is a handy option in the menu for showing the URL's which will need for your widget definition to define the url attribute. This gives you two URL's, either a NRPC or a HTTP url. Copy one of these across to your widget definition.

Creating a Widget in the Widget Catalog

Open the widget catalog in Notes. Click on the "Add Widget to Catalog" to create a new widget. Give your widget a title and also create a category. The category is important later in the process when you want to choose what library or libraries you want to install in your client. So you need to decide if you want to group libraries in one category together or if you are going to have one category per library, it's entirely up to you. For this simple use case we just have one library so will we use a category called "XPage Sample Library". Next you can choose which platforms you want your widget to run on, there are a number of options from Expeditor to Notes if you wish to restrict the widget to certain platforms. Next check the "Plug-ins and Features" option as this is our preferred widget type for an XPage Library.




Next you need to attach an XML definition that describes your widget and tells the client what to do with the widget when it is provisioned to the user .Here is a sample extension.xml file that is used to deploy this Sample XPage Library.
What to take note of here is the URL property, this tells the widget where it can find the actual features and plug-ins it needs to install. These are placed in an eclipse update site nsf which is used as a host Notes application for the features and plug-ins. Follow the instructions in the next section to create that update site and find the URL.

Properties that are of interest.
url="" -This can be either a http/nrpc/file URL that points to your updatesite nsf

hideThumbnail="true" -Flag to tell widget to hide the widget in My Widgets sidebar pane. It will only be shown if the user chooses "Show All" in the MyWidgets sidebar

match="perfect" -Guarantees that provision engine will attempt to install the exact version that you have specified

shared="true" -Provided that shared="true" is set in the install manifest snippet ,as below, the plug-in is installed to Notes_install_dir\framework\shared\eclipse. If there is no write access to that directory, the plug-in is installed to Notes_install_dir\data\workspace\applications. For information about install manifests, see the "Lotus Expeditor doc on Using the provisioning manifest".

Enabling the Widgets in your Notes Client Manually

If your administrator has given you the details of the widget catalog server to connect to, then the quick way to enable Widgets, is to go to File->Preferences->Widgets and fill in the fields. Click Apply so it searches for Categories. You can then select the categories you wish to install so if your administrator has told you which category has the XPage Library you need, you simply check the category and it will begin to download the widgets contained in that category.





Alternatively an administrator might just send you an XML definition by email which you can drag across to the MyWidgets sidebar

Enabling the Widget Catalog using a Policy

If you are an administrator then you can create a desktop policy which enforces what widget catalog server a client must use and also what categories to install on the clients machine.

Run Domino Administrator, in the People & Groups tab, click on Policies, Add Policy. Enter a name for the policy.

In the Desktop field, click New, that creates a new Desktop settings policy.
Enter a name for the Desktop Settings policy, and save it.
Then switch to the Widgets tab and change the configuration options:




Save the Desktop Settings policy.
Further details on those options are in Controlling Widgets and Live Text access using Domino policy.

In the outer policy, change the current Desktop Settings policy to the policy you just created.
Then in the Policy Assignment tab, choose the applicable users or groups,
or alternately save the Policy and assign the policy to the user or group [select People (or Groups), right-click on the person and choose Assign Policy, choose the policy from the dropdown and click ok].

You can also add the Policy User's Person doc in the Administration tab\ Policy Management & Assigned Policy.


The next time the user starts Notes the library will be installed automatically.

Installing the Widget

Whether you are installing the library manually or it has been pushed down by an administrator, what you should see when the library is being installed is the following dialog asking do you want to install the feature and plug-ins.





You choose to install this plug-in and it prompts you to restart your notes client for the updates to take effect.




Next open the NSF application that depends on the library that you have installed and see that it works as it should.

Deployment Security

The security objective for XPages Java security is to manage Java code that is loaded from an NSF. The model is based on trusting the XPages Runtime classes and not trusting any Java classes that are stored within the application NSF. When the XPages Runtime is processing a request, a mix of Java classes from the Runtime and the NSF may be on the execution stack and any one time. If there are any untrusted classes from the NSF on the execution stack the XPages Java Security Manager will be triggered to check if the current protected operation being executed is allowed.

As XPages Library Plug-ins will in effect provide part of the XPages Runtime, the Java classes that make up these libraries need to be trusted to distinguish them from the untrusted classes that are loaded from an NSF.

Any plug-in that contributes to one of the eclipse extension points provided by the XPages Runtime plug-ins will be loaded by the XPages runtime, and trusted by the XPages Java Security Manager. In addition any dependancy that those plug-ins use will also be loaded and trusted. Note that not every plug-in that contributes to an extension point can be referenced from code stored within the NSF. There is a special XspLibrary extension point that may be contributed to the XPages Runtime. If a plug-in provides the XspLibrary extension point, then classes in that plug-in will be available to code within the NSF and may be directly invoked from XPages and script libraries. Otherwise the references will result in ClassNotFoundException Java exceptions. Also, any plug-in dependencies that the XPages Library Plug-in declares may also be available to code within the NSF (depending on whether the plug-in is configured to "Reexport this dependency").

Given this high degree of trust and flexibility, it is very important that an Administrator tightly control which Plug-ins are installed onto their Servers and Client Workstations.

Administrator should use the operating and file system security to control who can install XPages Library Plug-ins onto their Servers and use the Notes Domino Policy controls and deployment features of the Widget Catalog to manage which Plug-ins user can download and install to their Notes Client.

The location of the Plug-in install can be controlled via the shared=true/false option in the extension.xml for the Widget that is to associated with the Plug-in in the Widget Catalog. See the "Creating a Widget in a Catalog" and "Enabling the Widget Catalog using a Policy" sections above for more details.

For the Domino Server, and Notes Client, while the XPages Library Plugi-ins can be installed anywhere and trusted, the following install locations are recommended to ensure the XPages Library Plug-ins continue to be trusted in future releases. Also note that the contents of Domino_install_dir\osgi will be deleted during Domino Server upgrades.

Domino Server
Domino_install_dir\data\domino\workspace\applications\eclipse\plugins

Notes Client , or Multi-User install where the Plug-is to be shared
Notes_install_dir\data\workspace\applications

Notes Client (Multi-User Install where you only want certain XPages Library Plug-ins available to certain users)
Notes_install_dir\data\workspace\applications

Resources

More information on the Widget Catalog and the other topics discussed in this article can be found at "Creating the widget catalog".